/**
 ******************************************************************************
 * @file           : bsp_timer.h
 * @brief          : TIMER Driver Header File (STM32H7xx)
 ******************************************************************************
 * @attention
 *
 * 定时器驱动程序头文件
 * 功能：
 *   - 软件定时器（基于SysTick，1ms精度）
 *   - ms/us级延迟函数
 *   - 系统运行时间统计
 *   - 硬件定时器（基本定时、PWM、输入捕获）
 *
 ******************************************************************************
 */

/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __BSP_TIMER_H
#define __BSP_TIMER_H

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/
#include <stdint.h>

/* Exported types ------------------------------------------------------------*/
/**
 * @brief 定时器错误码枚举
 */
typedef enum
{
    TIMER_OK = 0,               /*!< 成功 */
    TIMER_ERROR_PARAM,          /*!< 参数错误 */
    TIMER_ERROR_NOT_INIT,       /*!< 未初始化 */
    TIMER_ERROR_HAL             /*!< HAL库错误 */
} TIMER_Error_e;

/**
 * @brief 定时器工作模式枚举
 */
typedef enum
{
    TIMER_MODE_ONCE = 0,        /*!< 单次模式：定时到后停止 */
    TIMER_MODE_AUTO = 1         /*!< 自动模式：定时到后自动重装 */
} TIMER_Mode_e;

/**
 * @brief 定时器状态枚举
 */
typedef enum
{
    TIMER_STATE_IDLE = 0,       /*!< 空闲状态 */
    TIMER_STATE_RUNNING,        /*!< 运行状态 */
    TIMER_STATE_STOPPED,        /*!< 停止状态 */
    TIMER_STATE_ERROR           /*!< 错误状态 */
} TIMER_State_e;

/**
 * @brief 软件定时器结构体
 */
typedef struct
{
    volatile uint8_t mode;      /*!< 工作模式 */
    volatile uint8_t flag;      /*!< 定时到达标志 */
    volatile uint32_t count;    /*!< 实时计数器 */
    volatile uint32_t preload;  /*!< 自动重装值 */
} SoftTimer_t;

/* Exported constants --------------------------------------------------------*/
/* Exported macro ------------------------------------------------------------*/
/* Exported variables --------------------------------------------------------*/
extern volatile int32_t g_system_time_ms;   /*!< 系统运行时间（ms） */

/* Exported functions --------------------------------------------------------*/

/**
 * @brief       定时器模块初始化
 *
 * @param       无
 *
 * @retval      无
 *
 * @note        初始化SysTick和硬件定时器
 */
void timer_init(void);

/**
 * @brief       定时器模块反初始化
 *
 * @param       无
 *
 * @retval      无
 *
 * @note        关闭定时器
 */
void timer_deinit(void);

/**
 * @brief       ms级延迟
 *
 * @param[in]   ms - 延迟时间（毫秒）
 *
 * @retval      无
 *
 * @note        可被中断打断
 */
void timer_delay_ms(uint32_t ms);

/**
 * @brief       us级延迟
 *
 * @param[in]   us - 延迟时间（微秒）
 *
 * @retval      无
 *
 * @note        不可被中断打断
 */
void timer_delay_us(uint32_t us);

/**
 * @brief       启动软件定时器（单次）
 *
 * @param[in]   id - 定时器ID（0~7）
 * @param[in]   period_ms - 定时周期（毫秒）
 *
 * @retval      TIMER_Error_e - 错误码
 *
 * @note        定时到达后停止
 */
TIMER_Error_e timer_start(uint8_t id, uint32_t period_ms);

/**
 * @brief       启动软件定时器（自动重装）
 *
 * @param[in]   id - 定时器ID（0~7）
 * @param[in]   period_ms - 定时周期（毫秒）
 *
 * @retval      TIMER_Error_e - 错误码
 *
 * @note        定时到达后自动重新开始
 */
TIMER_Error_e timer_start_auto(uint8_t id, uint32_t period_ms);

/**
 * @brief       停止软件定时器
 *
 * @param[in]   id - 定时器ID（0~7）
 *
 * @retval      TIMER_Error_e - 错误码
 *
 * @note        无
 */
TIMER_Error_e timer_stop(uint8_t id);

/**
 * @brief       检查软件定时器是否到期
 *
 * @param[in]   id - 定时器ID（0~7）
 *
 * @retval      uint8_t - 1=到期, 0=未到期
 *
 * @note        到期后自动清除标志
 */
uint8_t timer_check(uint8_t id);

/**
 * @brief       获取系统运行时间
 *
 * @param       无
 *
 * @retval      int32_t - 运行时间（毫秒）
 *
 * @note        无
 */
int32_t timer_get_runtime(void);

/**
 * @brief       计算时间差
 *
 * @param[in]   last_time - 上一次记录的时间
 *
 * @retval      int32_t - 时间差（毫秒）
 *
 * @note        处理溢出情况
 */
int32_t timer_check_runtime(int32_t last_time);

/**
 * @brief       硬件定时器初始化
 *
 * @param       无
 *
 * @retval      TIMER_Error_e - 错误码
 *
 * @note        初始化基本定时器
 */
TIMER_Error_e timer_hw_init(void);

/**
 * @brief       启动硬件定时器
 *
 * @param       无
 *
 * @retval      TIMER_Error_e - 错误码
 *
 * @note        无
 */
TIMER_Error_e timer_hw_start(void);

/**
 * @brief       停止硬件定时器
 *
 * @param       无
 *
 * @retval      TIMER_Error_e - 错误码
 *
 * @note        无
 */
TIMER_Error_e timer_hw_stop(void);

/**
 * @brief       获取硬件定时器状态
 *
 * @param       无
 *
 * @retval      TIMER_State_e - 定时器状态
 *
 * @note        无
 */
TIMER_State_e timer_hw_get_state(void);

/**
 * @brief       打印定时器状态
 *
 * @param       无
 *
 * @retval      无
 *
 * @note        用于调试
 */
void timer_print_status(void);

#ifdef __cplusplus
}
#endif

#endif /* __BSP_TIMER_H */
